Goal

Previously, when we resolved doc handles in a draft, we only did this once. Switching branches or scrubbing through history required remounting the editor every time to re-resolve the doc handle. This PR makes the resolution reactive, so you don’t lose UI state when switching branches, and scrubbing becomes much smoother.

Implementation

In patchwork-system we wrap repo in a generic proxy that translates repo.find into "repo:handle-descriptor" request that other providers can respond to. A handle descriptor looks like this:

export type DocHandleDescriptor = {
  url: AutomergeUrl;
  cloneUrl?: AutomergeUrl;
};

By default, a document URL maps to itself, but providers can implement custom mappings. For example, a draft creates a clone of each document it contains; when a document is requested within the draft, the provider responds with the clone’s URL. The repo turns the returned doc handle descriptor into a doc handle that looks like the original (its url still reports the original), but reads and writes are delegated to the clone.

This PR makes the doc handle emit an artificial change event when it’s remapped to another doc, for example when the user switches drafts. To an editor, a branch switch looks like any other document change.

One exception: for editors that implement undo/redo, like tldraw and CodeMirror, the branch switch needs to reset the history stack. We solve this with the scopeReplaced flag introduced with sub doc handles: any artificial change event triggered by a remapping sets scopeReplaced = true.